fix(cli): keep overlap waivers local to marked text - #3464

Preview deployment for your docs. Learn more about Mintlify Previews.

💡 Tip: Enable Workflows to automatically generate PRs for you.

Follow-up on the same scene-4 case, after tracing why check missed it originally. The code here is right; the concern is the recommended invocation in the skill docs.

The caption gate runs only at the declared seeks, not at the merged layout grid.
checkPipeline.ts:152 merges captionSamples into layoutSamples, which reads like the gate gets the union. It doesn't: geometryRequest (checkPipeline.ts:216) returns null unless grid.captionSamples.includes(time) matches exactly. So caption_zone_collision is evaluated at exactly the 10 declared times and nowhere else.

Those 10 times are a fixed fraction list, so spacing scales with duration.
gateSampleTimes maps each fraction to fraction * duration (checkPipeline.ts:125). seek=.05,.15,…,.95 is therefore a uniform grid of period 0.10 * duration. On the 53.0s changelog film that is one probe every 5.3s.

Consequence on the exact defect that motivated this PR. The scene-4 card is visible 2.86s. A 2.86s window against a 5.3s grid intersects with probability 2.86 / 5.3 ≈ 54%. So the gate catches the case it was built for a bit better than a coin flip, and gets worse as films get longer: at 90s the spacing is 9s and the same defect drops to ~32%.

The good news, since it is easy to assume otherwise: caption_zone_collision is deliberately not in PERSISTENCE_TIERED_CODES (layoutAudit.ts:195-205), so applyPersistenceTier returns it untouched and the occurrences <= 1 info cap never applies. One hit is enough, and it reports at the flag's severity=error. The gap is purely detection probability, not severity.

Two ways to close it, both cheap:

1. Beat-aligned absolute seeks. The slides already carry data-start and captions.json carries the caption timings, so the interesting instants are known at build time and coverage becomes deterministic rather than probabilistic.
2. Or keep the uniform grid and just make spacing shorter than the shortest element lifetime. For a 53s film with ~2.9s beats that means ≥ 19 seeks rather than 10.

(1) is the one I would take, since it stays correct as film length changes and (2) has to be re-tuned every time the format does.

Verified at origin/main 95e1ac9 and against this PR at e9bc6b16; the 2.86s and 53.0s figures come from the fire-5 changelog build.

— Rames

The 25-point grid checks out: .02,.06,…,.98 is step 0.04, 25 probes, max interior gap 0.04 * duration, and the leading/trailing gaps are 0.02 * duration so they're strictly smaller. At 60s that's 2.4s < 2.86s, deterministic. Mechanical beats hand-calculated fractions, agreed.

One edge worth closing while you're in here: the 60s cap is prose, not an invariant. SKILL.md:51 says "Budget: 45-60s total", and I couldn't find anything that enforces it — no duration guard in the skill scripts, none in the CLI. Fire 5 came in at 53.0s against that same budget, and theme count moves with commit volume week to week.

That matters because the guarantee is duration-dependent in exactly the way the ten-point grid was, just with a friendlier constant. At 75s the gap is 3.0s and the original 2.86s case silently goes back to being a coin flip — and a contract test that pins "25 points" plus "≤2.4s max gap" computed at a fixed duration would still be green while it happened.

Two ways to make the test mean what it says:

1. Derive the seek count from the actual duration against a max-gap target, so the invariant is "gap ≤ 2.4s" rather than "25 points happen to give that at 60s".
2. Or keep the fixed 25 and assert the duration bound where the seeks are chosen, so an over-budget film fails loudly instead of quietly losing coverage.

Either is fine. The thing I'd avoid is having the only thing standing between the grid and under-sampling be a sentence in a docs budget.

— Rames